Ultra Pack

home *** CD-ROM | disk | FTP | other *** search

/ Ultra Pack / UltraComputing Technology Demos and Tools.iso / solidifier / doc / lava.doc < prev

Wrap

Text File | 1995-12-06 | 51.2 KB | 1,609 lines

26-July-1995 LAVA documentation (V1.0) INTRODUCTION LAVA is a program for manipulating 3D objects. Its original purpose was to test the XGL Application Programmer Interface (API) to help debug new hardware. It has grown to be a good way to demonstrate 3D graphics. Eventually it will become a tool for modifying 3D models. The original program was conceived by Scott R. Nelson of Sun Microsystems and an initial version was implemented by John Lilly, a Stanford University student, who worked as a summer intern for Sun in 1992. Enhancements were made by Scott R. Nelson with some of the NURBs code by Ranjit Oberoi and a few other odds and ends by Bob Schumacker. The program is still far from complete. The tool was later enhanced and redesigned by Yakov Kamen, Alex Metzler, Leon Shirman and Kirk Brown when it was renamed LAVA because of its new features and applications. For additional information about specific attributes beyond the simple descriptions found here, refer to the XGL 3.0 Programmer's Guide or Reference Manual. STARTING LAVA Because LAVA is written in XGL, it will run on any Sun workstation with a color display. However, it only runs efficiently on 3D graphics accelerators. It is still useful for looking at simple models on 8-bit displays, but the lack of double-buffering makes rendering of solids using motion quite slow. Eventually the code will be updated to detect 8-bit systems and to use indexed mode with wireframe as the default object display form. It runs well in wireframe mode on the TGX. LAVA may be started by typing the program name (lava). When started with no command line options, it starts up with a 500 by 500 window displaying a colored cube on a black background. LAVA has the following command line options: -single Start up in single-buffered mode instead of the default double-buffered mode. Use this for 8-bit displays. -file Specify the file to be loaded. This may have any of the following extensions: .obj Wavefront format .off DEC Object File Format .shad Sun Shader format (ancient) .mdl LAVA model script For controlled demos, start up the program using any name other than "lava" and it will come up using a full screen window using the name "3DOM", pronounced "threedom", which stands for Three- Dimensional Object Manipulator. This version is safe for any nieve user if given proper .mdl files. MOTION Objects may be moved in several different ways. On systems with control dials, the object can be moved using the dials. The dials are assigned as follows: dial 0 Rotate about the X axis dial 1 Rotate about the Y axis dial 2 Rotate about the Z axis dial 3 Scale the object dial 4 Translate along the X axis dial 5 Translate along the Y axis dial 6 Translate along the Z axis dial 7 Does nothing. The object may also be moved using the mouse. With the cursor in the graphics window, press the "select" mouse button (usually the left button) and the object can be rotated about the X and Y axes by moving the mouse. Press the "adjust" mouse button (usually the middle button) and the object may be scaled when the mouse is moved up and down. There is currently no way to translate using the mouse. Note that mouse motion is disabled when picking is enabled. In the current version (V2.0), if the mouse is moving when you let go of the object, it will keep moving in that direction. To stop the motion, either hold the object still for a while or just click once, quickly in the window. The object may also be rotated using the controls in the motion menu. These controls allow the object to be rotated either a specified number of frames or continually using the "free run" button. More will be said about these controls in the controls section below. Raster images may also be moved by the mouse. In this case, pressing any mouse button effectively attaches the image to the cursor as it is moved. Releasing the mouse button leaves the image at its current position. MENU BUTTONS There are 4 menu buttons across the top of the frame and one text field in the footer. The buttons are as follows: Controls Puts up a menu with 5 buttons, three of which bring up submenus. Each final menu button brings up a control panel with controls over various attributes and settings. There are 20 total control panels available. File Allows new objects and models to be loaded. Also allows objects and model parameters to be saved. Props Contains the performance panel, an incomplete edit menu, a short help document and an About panel listing the authors. Quit A simple way to exit the tool. The text field at the left of the footer displays the current object name. THE CONTROLS MENU The Controls menu allows the user to modify the attributes of the object being displayed. Each control panel contains buttons, sliders and/or text fields that allow attribute values to be set. Most of the controls that offer choices change the default so that clicking on the button cycles through the choices. This is done as a convenience for the user. Certain choices stay with one default if the other values might have undesirable consequences (for example, Raster OP). Use the menu button to select a specific setting. The controls menu contains the following 5 menu buttons: Part Selection Per Part Attributes Other Attributes Settings & COntrols Demo The Per Part Attributes pull right menu contains the following 7 menu buttons: Render Options Markers Lines Front Surface Back Surface Edges NURBS The Other Attributes pull right menu contains the following 6 menu buttons: Picking Lighting Depth Cue Texture Mapping Model Clipping Annotation Text The Settings & Controls pull right menu contains the following 5 menu buttons: Global Settings Motion View Environment Raster The 20 control panels are defined as follows: Part Selection This menu allows you to specify which parts are displayed and which part is the current part. Select All This button selects all parts to be displayed. Deselect All This button deselects all parts so that none of them are displayed. It is assumed the user will then select one part to be displayed. Current Part: Specifies which is the current part, to which any part-specific attribute settings will apply. Object Parts: This scrolling list contains the names of all parts in the model. The first item is always "Global", which draws nothing, but affects attributes for all parts. Any attribute for a specific part that has been set by the user or by a model command file will not be affected by global attribute changes. Clicking on a highlighted name turns off the part. Clicking on an unhighlighted name turns on the part and selects it as the current part. To make a displayed part the current part requires a double click. Holding the select button down while moving up and down selects or deselects whichever names are touched. Note that Select All and Deselect All both cause the current part to be "Global". Render Options This menu is for setting rendering attributes. It may apply for either the entire object (Global) or per part. Primitive Type: You may display the object or part as a solid, wireframe, or as markers at the vertices. Default is Solid. Face Culling: Face culling off means that both front and back faces will be rendered. Turning culling to Front means that XGL will only draw back faces, and vice versa. Default is Off. Face Dist(inguishing): When this is off, properties for both front and back surfaces are taken from the Front Surface Properties menu. Turning it on causes the Back Surface Menu to become selectable. Default is Off. Raster OP: Allows you to choose which raster operation is performed. Most settings don't make sense while rendering. Default is Copy. HLHSR Mode: This allows you to turn Hidden Line and Hidden Surface Removal on and off. Default is on. Markers This menu is used to set marker properties when the object or part is being displayed in MARKER mode. It may apply for either the entire object (Global) or per part. Marker Type: Allows the user to specify which XGL pre-defined marker is used to represent each point. Choices are: Dot, Plus, Asterisk, Circle, Cross, Square, Bowtie NE (goes Northeast to Southwest), or Bowtie NW (Northwest to Southeast). Default is Dot. Marker Color: Used to set the marker color, if the Color Selector switch is set to Context. There must be three floats on this line to be recognized. Default is green. (0.0 1.0 0.0) Antialiasing: For no antialiasing (jaggy lines or dots) turn this off. For markers all by themselves, the best setting is to blend to constant background. For markers and lines mixed with solids, the best setting is to blend to arbitrary background. Default is OFF. Scale Factor: This determines the size of each marker. It doesn't do anything to the Dot marker. Default is 10.0. Color Selector: Context means that markers should be the same color as their part color. If vertex colors were implemented, then selecting the Point option would mean that the markers would be the same color as their vertex is specified to be. Default is Context. Lines This menu may be used to set line properties when the object or part is being displayed in WIREFRAME mode. It may apply for either the entire object (Global) or per part. Line Color: Putting exactly three floats on this line allows you to set the line color. Default is green. (0.0 1.0 0.0) Antialiasing: For no antialiasing (jaggy lines) turn this off. For lines all by themselves, the best setting is to blend to constant background. For lines mixed with solids, the best setting is to blend to arbitrary background. Default is OFF. Line Width: Allows the user to determine how many pixels wide (or fraction thereof) that lines are drawn. For lines greater than 1.0, the Endpoint Style and Join Style options become active. Expect lines wider than 1 to be significantly slower than single pixel lines. Default is 1.0. Endpoint Style: Select which of three styles are used for endpoints on wide lines: Butt, Square, or Round. Default is Butt. Join Style: Determines how lines are joined: Device Specific, Beveled, or Mitered. Default is Mitered. Miter Limit: When the Join Style setting is set to Mitered, this determines the miter limit. Default is 2.0. Line Style: Solid means that lines will be drawn only in the color specified by the Line Color field. Patterned will draw the lines in the color specified by the Line Color field and the pattern chosen by the Line Pattern selection. Alt Patterned will render the lines in a pattern specified by the Line Pattern selection and alternating between the colors Line Color and Alt Line Color. Default is Solid. Line Pattern: Described above in the Line Style entry, this may take on the values of Dotted, Dashed, Dashed-Dotted, Cgm Dotted, Cgm Dashed, Dash-Dot, Dash-Dot-Dotted, or Long Dashed. Default is Dotted. Alt Line Color: Also described above, this field must have exactly three floating-point numbers. The default is white. (1.0 1.0 1.0) Color Selector: This specifies whether line colors are determined by their part colors or by their vertex colors. Vertex colors are not currently supported, so this doesn't affect anything. Default is Context. Color Interpolation: This won't be a useful choice until vertex colors are implemented. Default is OFF. Front Surface This menu allows you to set surface properties for your object or part. It may apply for either the entire object (Global) or per part. Back properties only apply when face distinguishing is enabled in the render menu. Surface color: Specifies the color of the surface. Enter three floats on this line to specify a valid color. Default is white. (1.0 1.0 1.0) Fill Style: This determines how solids are drawn. All but solid are likely to be slower on most machines. Solid means that the object is drawn filled with its color. Hollow draws only the edges of each polygon, Empty draws nothing (unless edges are enabled). Stipple and Opaque Stipple render the object with patterns determined by the Stipple Pattern setting. Both Stipple fill styles will cause a severe degradation in performance, however. Default is Solid. Stipple Pattern: As mentioned above, this setting determines what pattern is used when the Fill Style is Stipple or Opaque Stipple. Default is a horizontal pattern. Color Selector: Default is Illumination Independent. Illum(ination): This specifies the illumination model: None means no illumination at all. Interp Color works exactly the same as None, since we don't have vertex colors. Per Facet causes the model to be rendered with flat shading, and Per Vertex will turn on Gouraud Shading. Default is Per Facet. Light Component: Specifies which of the three light components: ambient, diffuse or specular, are used in lighting. Each of the three may be turned on and off independently. The Default is all on. Ambient, Diffuse, Specular: These sliders determine the ambient, diffuse, and specular coefficients, respectively. Defaults: Ambient: 0.2 Diffuse: 0.8 Specular: 1.0 Specular Color: Specifies the color of the specular highlight. Enter three floats on this line to specify a valid specular highlight color. Default is white. (1.0 1.0 1.0) Specular Power: Specifies the specular power used in computing the specular highlight. Big number cause small specular highlights and small numbers cause big specular highlights. This number is used exponentially, so expect the greatest changes between about 5.0 and 30.0. Default is 20.0 Transp Method: This specifies the transparency method used. "None" means no transparency. (default) "Screen Door" uses screen door transparency. "Blended" uses blended transparency. Transp. Blend Eq: If the transparency method is "blended", this specifies which blend equation to use. "None" does no blending. (default) "Constant BG" blends to a constant background. "Arbitrary BG" blends to an arbitrary background (best). "Add to BG" adds to the current background. Transparency: This slider determines the transparency. A value of 0.0 is fully opaque and a value of 1.0 is fully transparent. Back Surface This is identical to Front Surface, but for back surface properties. Transparency method and blend equation are not specified for back surfaces (the front settings are used). Edges When the model is rendered as a solid, you may turn edges on (display edges of each polygon) and set their attributes in this menu. It may apply for either the entire object (Global) or per part. Show Edges: OFF => Do not render polygon edges, XGL => Render edges using XGL to draw the edges, Software => Render edges using LAVA wireframe to draw the edges. Default is OFF. Edge Color: Specifies the color of the edges. This line must have EXACTLY three floating-point numbers on it (R, G, B) to set the edge color. Default is black. (0.0 0.0 0.0) Antialiasing: For no antialiasing (jaggy lines) turn this off. For lines all by themselves, the best setting is to blend to constant background. For lines mixed with solids, the best setting is to blend to arbitrary background. Default is OFF. Edge Width: Allows the user to determine how many pixels (or fraction thereof) in width that edges are drawn. Default is 1.0. Edge Style: Solid => Edges are drawn the color that is specified by the Edge Color field. Patterned => Edges are drawn with the color specified in the Edge Color field and the pattern specified by the Edge Pattern selection. Alt Patterned => Edges are drawn in the pattern specified by the Edge Pattern selection, but alternates colors between Edge Color and Alt. Edge Color. Both Patterned and Alt Patterned choices will cause a degradation in performance. Default is Solid. Edge Pattern: Described above, this can take the values of Dotted, Dashed, Dashed-Dotted, Cgm Dotted, Cgm Dashed, Dash-Dot, Dash-Dot-Dotted, or Long Dashed. Default is Dotted. Alt Edge Color: Described above, there must be exactly three floating-point numbers on this line. Default is white. (1.0 1.0 1.0) Silhouette: Doesn't work. What's more, this will cause a performance degradation. Default is OFF. SW Offset: Specifies the offset to use for software edges. The default value is 0.1, which is optimal for most cases, but may be wrong if the Z range is changed. Nurbs This menu is for setting nurbs properties. Approx. Method: Specifies whether the nurb tessellation is done in world coordinates (WC), virtual device coordinates (VDC) or device coordinates (DC), and whether to use metric, planar deviation or relative spacing. Default is constant parameter subdivision between knots. Approx Val U: Specifies the approximation value to use in the U direction. Approx Val V: Specifies the approximation value to use in the V direction. Param Style: Iso Curves shows the curves defining the surface. Note that this may not have a proper Z offset and is not likely to look as good as the edges. Show Tessellation draws edges around each generated triangle. Edges must be enabled in the edge menu before enabling this function. Increase Silhouette Tessellation causes a finer tessellation for parts of the object containing a silhouette edge. Iso Curve Placement: Specifies whether Iso curves are placed between knots or between limits. # Iso Curves U: Number of Iso curves in the U direction. # Iso Curves V: Number of Iso curves in the V direction. Picking Specifies picking modes and controls. When picking is enabled, the mouse may be used to select a part or facet depending on the picking mode. Use the select button to select a single part. Use the adjust button to get multiple parts (as in standard OpenLook). The first part selected (if there are more than one) also becomes the current part (see Part Selection to determine "first part"). When picking is set to By Facet, clicking on a single facet will change it to the facet highlight color. This is currently useful with the Edit menu. Picking: Picking is available either per part or per facet. Default is off. Note that cursor motion is not available while picking is enabled. Pick Aperture: The pick aperture specifies how many pixels in all directions from the center of the cursor qualify to be picked. Part Highlight Color: Specifies the color used in highlighting the part(s) picked. Highlight color may be set to any desired value. Facet Highlight Color: Specifies the color used in highlighting the facet(s) picked. If multiple parts or facets fall within the pick aperture all will be selected. When picking is disabled, the cursor rotates the object with the select button or changes the size (scales) with the adjust button. Lighting This menu is for setting lighting parameters. Up to 32 lights may be specified. All lights have different default settings, with the first three enabled by default. Light 0 is ambient and lights 1 and 2 are directional. Light 3 is a spot light and light 4 is positional. All the rest are directional with varying colors and directions. Light #: The number in this field (between 0 and 31, inclusive) corresponds to the light that you are currently working on (and whose attributes are currently displayed). To change the attributes for a specific light, just enter the light number in this field (or use the arrow keys). Switch: This determines whether the current light is on or off. Default is OFF. Type: Determines what sort of light the current light is. Choices are: Ambient, Directional, Positional, or Spot. Each sort of light has specific attributes which should be set (mentioned in the following text). Color: This specifies the color of the light, specified by exactly three floats (R, G, B). Direction: Determines what direction the light is pointing. There must be three floats, and this attribute is relevant only to Directional and Spot lights. Position: Determines position of the light source. Again, there must be exactly three floating-point numbers on this line. Valid only for Positional and Spot lights. Atten1 & Atten2: Specifies the light attenuation coefficients. Valid only for Positional and Spot lights. See the XGL manual if you want to understand how these work. Atten2 causes brightness to drop with distance. Angle: Specifies the spot light angle, in radians, at which, the light is cut off completely. This interacts closely with the spot exponent. Valid for Spot lights only. If the angle is small relative to the spread specified by the exponent, expect to see rendering artifacts at the edges of the spot light. Exponent: The spot light concentration exponent. Specifies how fast the intensity falls off as the distance increases. A value of 1.0 doesn't drop off much at all, a large value drops off very quickly forming a narrow beam. Valid only for Spot lights. Depth Cue This menu sets depth cuing parameters. Mode: Specifies whether depth cuing is linear, scaled or none. Use scaled for best effect. Default is None. Color: Determines depth cue color. Default is black (0.0 0.0 0.0) but should be the background color. Front Ref. Plane: Specifies the position of the front reference plane. The front reference plane is constrained to always be greater than the back reference plane. Default is 0.2. Back Ref. Plane: Specifies the position of the back reference plane. The back reference plane is constrained to always be less than the front reference plane. Default is -0.2. Max. Scale: Specifies the ratio of object color to depth-cue color at the front reference plane. Default is 1.0. Min. Scale: Specifies the ratio of object color to depth-cue color at the back reference plane. Default is 0.1. Use BG Color Determines whether to use the color specified in the second field or to depth-cue to the background color. Texture Mapping This menu sets texture mapping paramters. Texture On/Off: Turns texture mapping on or off. To view a textured object, a texture map must be previously loaded using the "Load Texture" option of the File menu. Binding: Performs automatic binding of texture coordinates to the vertices of an object. Must be performed if original vertices don't contain data values. Texture Method: Either vertex-level, or standard pixel texture mapping. Approx Type: Used for vertex-level texture mapping only. Num Segments specifies into how many segments to subdivide each triangle side. Pixel Tolerance specifies allowable subtriangle size in pixels. Combined mode selects the smallest subdivision from the first two types. Subsegments: Used for vertex-level texture mapping only. Number of subsegments for Num Segments approximation type. Pixel Tolerance: Used for vertex-level texture mapping only. Subtriangle size in pixels for Pixel Tolerance approximation type. Model Clipping Up to 16 model clipping planes may be specified. # of Clip Planes: Specifies how many model clip planes are enabled. Default is 0. Coords: For each model clipping plane a 3D coordinate specifies a point on the plane. Normals: Specifies a normal to the plane in the direction of the part of the model not to clip away. Note that the default values for each plane is unique such that adding a plane is visible with most objects. Annotation This menu may be used to determine how annotation text is rendered for an object. Annotation names are determined by part names in the data file. Show Annotation: Whether the object is annotated or not. Default is OFF. Antialiasing: For no antialiasing (jaggy lines) turn this off. For lines all by themselves, the best setting is to blend to constant background. For lines mixed with solids, the best setting is to blend to arbitrary background. Default is OFF. Char(acter) Height: Determines how tall the annotation text is. Default is 0.05. Slant Angle: Determines the slope of the annotation characters. Default is straight up (0.0). Up Vector: Default is (0.0 1.0). Color: Determines what color the text will be rendered. Default is green. (0.0 1.0 0.0) Style: The Line option will cause annotation lines to be drawn from the text to the part which it is pointing to. Normal mode will not render those lines. Default is Line. Pointer Length: This determines how far the text will be from the annotated part. Default is 1.0. Horizontal Alignment: Specifies how text is lined up horizontally. Choices are: Normal, Right, Left, and Center. Default is Normal. Vertical Alignment: Specifies how text lines up vertically. Choices are: Normal, Base, Bottom, Top, Half, and Cap. Default is Normal. Text Path: Determines which direction the text continues from its starting point. Choices are Right, Left, Up, and Down. Default is Right. Text Text is not implemented in the current code (V2.3.1). Global Settings This menu specifies global settings that don't fit well into other categories. Most may only be set once per frame displayed. Background Color: Sets the background color for the display window. Enter three floating-point numbers on this line. Default color is black. (0.0 0.0 0.0) Deferral Mode: Determines when things are drawn: As Soon As Possible (ASAP) or At Some TIme (ASTI). ASAP is slower for most accelerators. Default is ASTI. Double Buffered: Specifies whether drawing will be done in single or double buffered mode. The default setting for this attribute depends on whether or not double-buffering is available on the device. Stereo Mode: Allows the user to select stereo mode. The object gets drawn twice into the same buffer if stereo is not available. The default depends on the current mode of the window system. If the display is running in stereo mode, this attribute will be enabled. Someday this will be smart enough to detect that there is no stereo mode and will use the cheap red/blue mode. Reset all attributes Pressing this button resets all of the global attribute settings. This currently does not update the per-part attributes. Motion This menu is for setting motion/transformation parameters. Reset All: Resets the local and global matrices to identity. This does not stop motion or reset any motion values. Especially useful when the object has accidentally been translated off the screen and lost. Stop: Stop all motion. Start: Begin motion for the specified number of frames. Stop after that many frames. # of Frames: Specifies how many frames to display after pressing the start button. Most useful for slow hardware or very large models. Global XYZ-Axis: Specifies the angle of rotation (in degrees) for each axis of the global modeling matrix. Affected by the left (select) mouse button. Global Scale: Applies a scale to the object, using the global matrix. Affected by the middle (adjust) mouse button. Global Free Run: Specifies to draw continuously, updating the global matrix each frame. Global Stop Stops updates to the global matrix. If the local matrix is not in free run mode, this also stops all automatic motion. Reset Global Matrix Resets the global matrix to identity. Local XYZ-Axis: Specifies the angle of rotation (in degrees) for each axis of the local modeling matrix. Local Free Run: Specifies to draw continuously, updating the local matrix each frame. Local Stop Stops updates to the local matrix. If the global matrix is not in free run mode, this also stops all automatic motion. Reset Local Matrix Resets the local matrix to identity. Both local and global motion is available so that more complex motion can be easily specified. Note that moving the object using the mouse select button sets the X and Y local axis values and clears the Z axis value. Scaling using the mouse adjust button modifies the local scale setting. View This menu specifies how an object is viewed. Center XYZ: These sliders allow the object center to be moved to get either a more natural appearance or to purposely set the object off center. Object Center: Specifies how to center the object. To use the slider select Use Slider. To set the center to one of the 6 boundaries select plus or minus XYZ. Minus Y would put a car on its wheels, for example. Object Scale: Allows a choice of making the object exactly fit within the window (at the narrowest dimension) or to be half that size or to use its original size. Window bounds are -1.0 to 1.0. Object View Scale: Allows the overall image to be scaled without affecting perspective or other view parameters. Z-clip Scale: Specifies how the object is scaled in Z to avoid being clipped. This also affects the Z-buffer precision. Perspective: Adjusts the perspective value. Environment Settings Controls additional environment objects. Floor: To get a floor at the bottom of the object, enable one of these 3 settings. A solid fine grid is best for spot lights. A solid single square is best for other solid floors. Floor Color: Specifies what color the floor is. Floor Prim. Type: Specifies Solid or Wireframe. Wireframe floors have less overhead than solid, but don't look as good with shadows. Floor Position: Specify the position of the floor relative to the object. A value of 0.0 will touch the bottom of the object. You can slide it up for boats and such. "Shadow": Causes a fake shadow to be drawn. This is accomplished by drawing the entire object again in the shadow color and scaling by 0.0 in Y to squash everything into one plane. This is NOT a correct shadow, but looks good with overhead lighting. The shadow is only available when a floor is drawn. Shadow Darkness: Specifies the percentage of floor color to use in drawing the shadow. Raster Settings Controls how raster images are viewed. Left Offset This slider adds an offset to the left side of the image. It specifies to skip pixels to the left of the image. Top Offset This slider adds an offset to the top of the image. It specifies to skip pixels at the top of the image. Width Specifies how much of the image to view in the horizontal direction. Height Specifies how much of the image to view in the vertical direction. Switch To Raster The default mode is Off, which means to draw the object in 3D mode. Save Pixels means to take the current image being to displayed and store it as a raster image. Further manipulations are now done in raster mode. Stochastic Sample causes the image to be sampled 8 times with a sub-pixel jittered offset. If the object is in motion at the time you will also get motion blur. Reset Image Position Use this to get the image back in the upper left corner when you have accidentally slid it off the screen and can't find it again. Demo This special menu has 6 simple controls that are supposed to do the "right thing" without concern for interaction with other controls. All of these will update the appropriate other menus that they affect. Solid/Wireframe Switches between solid and wireframe mode. Line Antialiasing Turns line antialiasing on and off. Edges Turns edges (including nurb tessellation) on and off. Transparency Switches between the two transparency modes and solid rendering. Depth-cue Turns depth-cue on and off. Model Clipping Turns model clipping on and off. FILE MENU The File menu allows the user to load models to be viewed. It also allows models (and attributes), objects and raster images to be saved to be reloaded later. Each of the general load and save control panels display a scrollable list of potential files or directories to choose from. Double-clicking on the desired file loads that file. Double-clicking on a directory changes to that directory. The File controls are as follows: Load Model Loads in a model script (.mdl). This contains commands to set all attributes as well as to specify the object to be loaded. It may contain motion directives as well. Details of what may go in one of these scripts are found below. Load Object Load an object from one of the currently supported object file formats. Wavefront objects are found in files with the .obj extension. DEC Object File Format objects are found in files with the .off extension. Sun Shader files may also be loaded (.shad extension). PTC ProEngineer objects are stored in files with the .slp extension. Nurb files have a .nu or .sof extension. Sun Raster files may also be loaded if they have one of the following extension: .im32, .im24, .im8 or .ras. Note that all attributes get reset whenever an object is loaded. Load Texture Loads in a raster file, describing a texture map. Save Model Save the current attribute settings and model specification. This is supposed to save everything so that the exact same image will be seen when reloaded. It is not 100% perfect, but it does work most of the time. Save Object Save the current 3D model in Wavefront format. Doesn't work with all models, especially nurbs. Save Raster Save the current screen image as a 24-bit Sun Rasterfile. This also switches to raster mode if not already in that mode. Load Color Cube Loads a simple cube, identical to that used at when the program is first started. PROPS MENU The properties menu currently contains four buttons. Performance data specifies how many of each type of primitive are being displayed, and how fast this data is being displayed. Edit contains an incomplete edit menu that is still under construction (V2.0). Help contains a brief overview of how to use LAVA. About contains information about the program authors. The fields in the Performance Data panel are as follows: Triangles: The number of triangles being displayed. When this field has a number and the Lines and Points fields are zero, the primitives per second field is the triangles per second number. Lines: The number of lines being displayed. When this field has a number and the Triangles and Points fields are zero, the primitives per second field is the lines per second number. Note that the typical polyline length is very short, with the maximum length no longer than the number of lines it takes to go around the edges of a facet without drawing an edge that already belongs to a neighboring facet. Points: The number of points being displayed. When this field has a number and the Triangles and Lines fields are zero, the primitives per second field is the points per second number. If the marker type is other than Dot, this number may not have a lot of meaning. Frames/sec: How many times the picture is redrawn per second. The program waits until the time specified by the Sample Rate has been exceeded, then divides the number of frames by the time that has elapsed. High performance accelerators should be able to draw simple objects at the monitor refresh rate. Primitives/sec: How many primitives per second are being drawn. Primitives are the sum of the Triangles, Lines and Points. Two of these three fields should be zero to get a valid performance number for a given primitive type. Note that this number will go up if you switch from double to single buffered mode because the system will no longer wait to synchronize with vertical retrace (but the screen repaint will not appear smooth). Parts: Specifies how many separate parts the object contains. Each individual part may have separate attributes. An object with more parts has more overhead in the display loop than an object with fewer parts. Otherwise, this number has no direct impact on the primitives per second number. Facets: How many facets are being displayed. The current version of code (V2.0) turns each facet into a triangle strip with a restart at the beginning. No attempt is made to chain these together into longer strips. This number has no direct impact on the primitives per second number and is only present to provide just a little more information about the model. Sample rate (sec): How often the frames per second and primitives per second fields are updated. Because of the overhead of updating the panel, the longer you wait, the more accurate the numbers will be. The default value is 2 seconds, which is a good compromise between the overhead of updating the panel and the attention span of the average viewer. This field may be set by the user. COMMAND SCRIPTS Nearly all attributes that may be set in the Controls menu may also be set in a command script. Command scripts are contained in model files (.mdl). The command lines must contain a single command per line, although extra whitespace is allowed anywhere. Commands that require more than one line must have a backslash character (\) as the last character of the line. Comments use the exclamation point character (!) and last to the end of the current line. In general, everything after a valid command on a line is ignored. A command script may be loaded using the Load Model button on the File menu or the program may be started up under control of a command file as follows: lava -file test_file.mdl Note that all but part names are totally case insensitive. Part names MUST match upper and lower case. The easiest way to get started on creating a .mdl file is to load the desired object, set the attributes you want, then save it using the Save Model command. Then just edit the results until the desired effect is achieved. In general, any numeric value following an equals sign (=) may also be followed by an operator-equals sign (+=, -=, *=, or /=). This allows loops to be created where values such as color or line widths can change as each image is rendered. The following list contains all of the currently supported commands, in an order matching the control menu. Any item that allows a choice of several values will have all choices listed in a pair of square brackets (e.g. [off on]). In the command script, exactly one of these choices must be used (and without the brackets). Floating-point and integer values are specified in these examples as <float> and <int> respectively. The numbers in the file may use any format that is acceptable to a standard C compiler. Part names may optionally be encased in double quotes, which are required if the part name has a space character in it. The following groups of attributes may be set on a global basis or on a per-part basis. To set either the global value or the part value of render.prim_type to solid, any of the following five formats are acceptable: render.prim_type = solid ! Sets global primitive type to solid render.prim_type Global = solid ! Sets global primitive type to solid render.prim_type "Global" = solid ! Sets global primitive type to solid render.prim_type part_1 = solid ! Sets part_1 to solid render.prim_type "part_1" = solid ! Sets part_1 to solid ! <= This is a comment, remember? Note once again that part names are case sensitive and may include spaces in some instances. Attribute commands to turn parts off and on: part.select <part name> part.deselect <part name> part.select_all part.deselect_all Attribute setting commands which may optionally be applied per part: render.prim_type = [wireframe markers solid] render.face_culling = [off back front] render.face_dist = [off on] render.raster_op = [clear set copy copy_inv invert and and_reverse \ and_inv nand or or_reverse or_inv nor xor equiv noop] render.hlhsr_mode = [off on] markers.marker_type = [dot plus asterisk circle cross square \ bowtie_ne bowtie_nw] markers.marker_color = <float> <float> <float> markers.antialiasing = [off constant_bg arbitrary_bg] markers.scale_factor = <float> markers.color_selector = [context vertex] lines.line_color = <float> <float> <float> lines.antialiasing = [off constant_bg arbitrary_bg] lines.line_width = <float> lines.endpoint_style = [butt square round] lines.join_style = [device bevel miter] lines.miter_limit = <float> lines.line_style = [solid patterned alt_patterned] lines.line_pattern = [ dotted dashed dashed_dotted cgm_dotted \ cgm_dashed dash_dot dash_dot_dotted long_dashed] lines.alt_line_color = <float> <float> <float> lines.color_selector = [context vertex] lines.color_interp = [off on] front_surf.color = <float> <float> <float> front_surf.fill_style = [solid hollow empty opaque_stipple stipple pattern] front_surf.stipple_pattern = [horizontal vertical diag_45 diag_135 \ grid_r grid_d horiz_dbl vert_dbl diag_45_dbl diag_135_dbl \ grid_r_dbl grid_d_dbl] front_surf.color_selector = [context facet illum_dep illum_indep] front_surf.illum = [none interp_color per_facet per_vertex] ! Note: Zero or more of the following three are allowed */ front_surf.light_component = ambient diffuse specular front_surf.ambient = <float> front_surf.diffuse = <float> front_surf.specular = <float> front_surf.specular_color = <float> <float> <float> front_surf.specular_power = <float> front_surf.transp_method = [none screen_door blended] front_surf.transp_blend_eq = [none arbitrary_bg constant_bg add_to_bg] front_surf.transparency = <float> back_surf.color = <float> <float> <float> back_surf.fill_style = [solid hollow empty opaque_stipple stipple pattern] back_surf.stipple_pattern = [horizontal vertical diag_45 diag_135 \ grid_r grid_d horiz_dbl vert_dbl diag_45_dbl diag_135_dbl \ grid_r_dbl grid_d_dbl] back_surf.color_selector = [context facet illum_dep illum_indep] back_surf.illum = [none interp_color per_facet per_vertex] ! Note: Zero or more of the following three are allowed */ back_surf.light_component = ambient diffuse specular back_surf.ambient = <float> back_surf.diffuse = <float> back_surf.specular = <float> back_surf.specular_color = <float> <float> <float> back_surf.specular_power = <float> edges.show_edges = [off on] edges.edge_color = <float> <float> <float> edges.antialiasing = [off constant_bg arbitrary_bg] edges.edge_width = <float> edges.edge_style = [solid patterned alt_patterned] edges.edge_pattern = [ dotted dashed dashed_dotted cgm_dotted \ cgm_dashed dash_dot dash_dot_dotted long_dashed] edges.alt_edge_color = <float> <float> <float> edges.silhouette = [off on] nurbs.approx_method = [const_param_subdiv_between_knots metric_wc \ metric_vdc metric_dc chordal_deviation_wc \ chordal_deviation_vdc chordal_deviation_dc \ relative_wc relative_vdc relative_dc] nurbs.approx_val_u = <float> nurbs.approx_val_v = <float> ! Note: Zero or more of the following three are allowed */ nurbs.param_style = iso_curves show_tess incr_silh_tess nurbs.iso_curve_placement = [between_knots between_limits] nurbs.iso_curves_u = <int> nurbs.iso_curves_v = <int> The following commands only apply on a global basis and may not have a part name keyword applied: picking.picking = [off on] picking.part_highlight_color = <float> <float> <float> picking.facet_highlight_color = <float> <float> <float> picking.pick_aperture = <int> ! Note: To specify light number 4, use "[4]" before the equals sign lighting.switch [0] = [off on] lighting.type [0] = [ambient directional positional spot] lighting.color [0] = <float> <float> <float> lighting.direction [0] = <float> <float> <float> lighting.position [0] = <float> <float> <float> lighting.atten_1 [0] = <float> lighting.atten_2 [0] = <float> lighting.angle [0] = <float> lighting.exponent [0] = <float> depth_cue.mode = [none linear scaled] depth_cue.color = <float> <float> <float> depth_cue.front_ref_plane = <float> depth_cue.back_ref_plane = <float> depth_cue.max_scale = <float> depth_cue.min_scale = <float> texture.switch = [off image video] texture.binding ! performs texture binding texture.approx = [num_seg pixel_tol combined] texture.subseg = <int> texture.pixel_tol = <int> texture.tau_func = <int> texture.update ! updates all texture parameters. Needed before draw model_clipping.num_planes = <int> !Note: To specify clip plane 3, use "[3]" before the equals sign model_clipping.coord [0] = <float> <float> <float> model_clipping.normal [0] = <float> <float> <float> annotation.show = [off on] annotation.antialiasing = [off constant_bg arbitrary_bg] annotation.char_height = <float> annotation.slant_angle = <float> annotation.up_vector = <float> <float> annotation.color = <float> <float> <float> annotation.style = [normal line] annotation.pointer_length = <float> annotation.horiz_alignment = [normal right left center] annotation.vert_alignment = [normal base bottom top half cap] annotation.text_path = [right left up down] global.background_color = <float> <float> <float> global.deferral_mode = [asti asap] global.double_buffered = [off on] global.stereo_mode = [off on] global.reset_attr ! This is like pressing the button motion.reset_transforms ! These are like pressing the button motion.stop motion.start motion.num_frames = <int> motion.global_x_rotate = <float> ! Note that rotations don't motion.global_y_rotate = <float> ! allow the op-equals format motion.global_z_rotate = <float> motion.global_scale = <float> motion.global_free_run motion.global_stop motion.local_x_rotate = <float> ! Note that rotations don't motion.local_y_rotate = <float> ! allow the op-equals format motion.local_z_rotate = <float> motion.local_free_run motion.local_stop view.center_x = <float> view.center_y = <float> view.center_z = <float> view.object_center = [use_slider plus_x minus_x plus_y minus_y plus_z \ minus_z none] view.object_scale = [half_screen full_screen original] view.view_scale = <float> view.z_clip_scale = <float> view.perspective = <float> env.floor = [none single_square coarse_grid fine_grid] env.floor_color = <float> <float> <float> env.floor_prim_type = [solid wireframe] env.floor_position = <float> env.shadow = [off on] env.shadow_darkness = <float> Additional motion control commands: position.reset_transforms ! Reset the local and global position transformation matrices. position.local_scale = <float> position.local_x_translate = <float> position.local_y_translate = <float> position.local_z_translate = <float> position.local_x_rotate = <float> position.local_y_rotate = <float> position.local_z_rotate = <float> position.global_scale = <float> position.global_x_translate = <float> position.global_y_translate = <float> position.global_z_translate = <float> position.global_x_rotate = <float> position.global_y_rotate = <float> position.global_z_rotate A special case exists for matrices: position.local_matrix = <16 floats> position.global_matrix = <16 floats> position.view_matrix = <16 floats> The matrices are stored when a Model file is saved so that an exact view can be restored. In general, these should be removed from the file with a text editor if you want to create a simple model file or motion script. The view matrix is not used directly, even though it does represent what is used in the program. The various numbers are extracted and matched to the fields from the view menu. Other commands: obj_colors.part_color "part name"= <float> <float> <float> For convenience, this will set the front surface color, line color and marker color for the specified part. This allows colors to be defined that are retained when changing between solid, wireframe and markers. load_object "object name" The object name can be a full path or the name of a file in the current directory. The file extension indicates what type of file it is. Doesn't currently work for other .mdl files. load_texture "texture file" Loads specified texture file. draw Draw the object once. Useful for motion loops. draw_no_clear Draw but don't clear the screen. Useful in single-buffered mode to put multiple objects in a scene. no_final_move Sets a flag that prevents a redraw at the end of the .mdl file when something is drawn using draw_no_clear. update_menus For long scripts, this makes sure that any displayed menus are updated at this point instead of waiting until the script is fully complete. loop <int> end_loop The loop/end_loop pair loops through the commands in between the number of times specified by the integer value. These may be nested up to 10 levels. It is a good idea to place a "draw" command inside the innermost loop. quit Exit from LAVA. Generally used by scripts loaded from the command line by test programs that would like the program to exit when the motion is complete. save_image Writes the current image out to a file named "ras.im32" in the current directory. Especially useful with multipass stochastic sampling (jittering). This could have a better interface, but was hacked in quickly for V1.2.3. jitter <int> end_jitter Begin a loop using up to 8 internal jitter offsets for multipass stochastic antialising of solid images. This produces a very nice effect, but the current implementation (V1.2.3) is a bit of a hack. The other end of the loop must have an end_jitter command, there must be a draw command somewhere inside the loop, and it is a good idea to enable no_final_move if you want to look at the resultant image. This process is currently extremely slow. jitter_offset = <float> <float> Available in case you don't like the predefined jitter values available with the jitter command. Needs a little more work to be useful. EXAMPLE The following is a simple motion example showing how a model command file might be built: ! ! Make the model move ! ! Best when using the default cube, since it is so simple ! motion.reset_transforms ! Reset all matrices position.reset_transforms draw render.prim_type = solid ! Draw a solid object for a while loop 3 loop 100 ! Move right while rotating position.local_x_translate = 0.002 position.local_x_rotate = 1.0 draw end_loop loop 100 ! Rotate without moving position.local_x_rotate = 1.0 draw end_loop end_loop position.reset_transforms render.prim_type = wireframe ! Draw wireframe for a while lines.line_width = 1 loop 5 loop 40 position.global_scale = 0.95 ! Shrink it position.global_x_rotate = 2.0 draw end_loop lines.line_width += 1.0 ! Make lines get fatter loop 40 position.global_scale = 1.0526 ! Expand it position.global_x_rotate = 2.0 draw end_loop lines.line_width += 1.0 end_loop !Done.